docs/development/Cmake usage.md

   1 # Cmake Usage
   2
   3 ## Introduction
   4
   5 This guide documents INAV usage of the `cmake` build tool.
   6
   7 ## Target Defintion
   8
   9 A target requires `CMakeLists.txt` file. This file contains one of more lines of the form:
  10
  11 ```
  12 target_hardware_definition(name optional_parameters)
  13 ```
  14
  15 For example:
  16
  17 ```
  18 target_stm32f405xg(QUARKVISION HSE_MHZ 16)
  19 ```
  20
  21 * The hardware is `stm32f405xg`, a F405 with a 1MiB flash
  22 * The name is `QUARKVISION` (a board that never reached production)
  23 * The optional parameter is `HSE_MHZ 16` defining the non-default high-speed external (HSE) oscillator clock.
  24
  25 ## Hardware names
  26
  27 As of INAV 4.1, the following target hardware platforms are recognised:
  28
  29 * stm32f405xg
  30 * stm32f411xe
  31 * stm32f427xg
  32 * stm32f722xe
  33 * stm32f745xg
  34 * stm32f765xg
  35 * stm32f765xi
  36 * stm32h743xi
  37
  38 The device characteristics for these names may be found at [stm32-base.org](https://stm32-base.org/cheatsheets/linker-memory-regions/).
  39
  40 ## Optional Parameters
  41
  42 The following optional parameters are recognised:
  43
  44 | Paramater | Usage |
  45 | --------- | ----- |
  46 | `SKIP_RELEASES` | The target is disabled for releases and CI. It still may be possible to build the target directly. |
  47 | `COMPILE_DEFINITIONS "VAR[=value]"` | Sets a preprocessor define. |
  48 | `HSE_MZ value` | The target uses a high-speed external crystal (HSE) oscillator clock with a frequency different from the 8MHz default. The `value` is the desired clock, for example `HSE_MHZ 24` |
  49
  50 Multiple optional parameters may be specified, for example `HSE_MHZ 16 SKIP_RELEASES`.
  51
  52 ## Target variations
  53
  54 A number of targets support multiple variants, either successive versions of the same hardware, or varations that enable different resources (soft serial, leds etc.) This is defined by adding additional `target_` lines to `CMakeLists.txt`. For example, the OMNIBUSF4 and its multiple clones / variations, `src/main/target/OMNIBUSF4/CMakeLists.txt`:
  55
  56 ```
  57 target_stm32f405xg(DYSF4PRO)
  58 target_stm32f405xg(DYSF4PROV2)
  59 target_stm32f405xg(OMNIBUSF4)
  60 # the OMNIBUSF4SD has an SDCARD instead of flash, a BMP280 baro and therefore a slightly different ppm/pwm and SPI mapping
  61 target_stm32f405xg(OMNIBUSF4PRO)
  62 target_stm32f405xg(OMNIBUSF4PRO_LEDSTRIPM5)
  63 target_stm32f405xg(OMNIBUSF4V3_S5_S6_2SS)
  64 target_stm32f405xg(OMNIBUSF4V3_S5S6_SS)
  65 target_stm32f405xg(OMNIBUSF4V3_S6_SS)
  66 # OMNIBUSF4V3 is a (almost identical) variant of OMNIBUSF4PRO target,
  67 # except for an inverter on UART6.
  68 target_stm32f405xg(OMNIBUSF4V3)
  69 ```
  70
  71 ## Adding (or removing) a source file
  72
  73 In the cmake system, project source files are listed in `src/main/CMakeLists.txt`. New source files must be added to this list to be considered by the build system.